迁移指南（Migration Guide）

0.14.0 版本概览

0.14.x 是一次重要升级：Flutter 侧旧 Dart Runtime 代码被移除，底层改为基于 C++ Runtime（通过 FFI）。

详情：

• Rive Native for Flutter

新增能力（重点）

• Rive Renderer
• Data Binding
• Layouts / Scrolling / N-Slicing
• Vector Feathering
• rive_common 被 rive_native 替代

说明（Note）：图形视觉与行为应保持一致，但接入 API 有明显变化。

要求（Requirements）

sdk: ">=3.5.0 <4.0.0"
flutter: ">=3.3.0"

必须在使用前初始化：

import 'package:rive/rive.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await RiveNative.init();
  runApp(const MyApp());
}

快速迁移清单

1. 升级 rive 到 0.14.x
2. 增加 RiveNative.init()
3. Rive / RiveAnimation → RiveWidget / RiveWidgetBuilder
4. 旧控制器体系 → RiveWidgetController 等新 API
5. 检查自定义 asset loader
6. 回归测试图形与交互

主要 API 变更

类移除与替代

• Rive / RiveAnimation → RiveWidget / RiveWidgetBuilder
• RiveAnimationController 系列 → RiveWidgetController
• StateMachineController → StateMachine
• RiveEvent → Event
• SMITrigger/SMIBool/SMINumber → TriggerInput/BooleanInput/NumberInput
• FileAssetLoader 旧体系移除（改为 File 构造时回调）

文件加载

• RiveFile 被 File 替代
• RiveFile.import → File.decode(...)
• mainArtboard → defaultArtboard()
• artboardByName(name) → artboard(name)

final file = await File.decode(bytes, riveFactory: Factory.rive);
final artboard = file.defaultArtboard();

Widget 迁移

• 旧：RiveAnimation.asset(...)
• 新：RiveWidgetBuilder 或 RiveWidget

状态机输入

stateMachine.trigger('myTrigger');
stateMachine.boolean('myBool');
stateMachine.number('myNumber');

支持嵌套路径：

stateMachine.boolean('myBool', path: 'nested/path');

Event

Event 现为 sealed class（如 OpenUrlEvent、GeneralEvent），可在 state machine 上注册监听器。

资源加载（Out-of-band）

assetLoader 不再支持 async lambda；需同步返回是否拦截，并在回调中自行完成 decode/注入流程。

已知暂缺能力（0.14.0）

• 自动 Rive CDN 资源加载
• speedMultiplier
• useArtboardSize
• clipRect
• isTouchScrollEnabled
• dynamicLibraryHelper

获取帮助

• Flutter 文档：https://rive.app/docs/flutter
• 社区：https://community.rive.app
• 仓库 Issue：https://github.com/rive-app/rive-flutter